heroku-client

What is heroku-client?

The heroku-client npm package is a JavaScript client library for the Heroku Platform API. It allows developers to interact with Heroku's services programmatically, enabling automation and integration with other tools and services.

What are heroku-client's main functionalities?

Authentication

This feature allows you to authenticate with the Heroku API using an API token. This is the first step to interact with Heroku services programmatically.

const Heroku = require('heroku-client');
const heroku = new Heroku({ token: 'YOUR_HEROKU_API_TOKEN' });

List Apps

This feature allows you to list all the applications associated with your Heroku account. The code sample demonstrates how to fetch and log the list of apps.

heroku.get('/apps').then(apps => console.log(apps));

Create App

This feature allows you to create a new Heroku application. The code sample shows how to create an app named 'my-new-app'.

heroku.post('/apps', { body: { name: 'my-new-app' } }).then(app => console.log(app));

Delete App

This feature allows you to delete an existing Heroku application. The code sample demonstrates how to delete an app named 'my-new-app'.

heroku.delete('/apps/my-new-app').then(response => console.log(response));

Get Config Vars

This feature allows you to retrieve the configuration variables for a specific Heroku application. The code sample shows how to fetch and log the config vars for 'my-new-app'.

heroku.get('/apps/my-new-app/config-vars').then(configVars => console.log(configVars));

Other packages similar to heroku-client

heroku-cli-util

The heroku-cli-util package provides utilities for building Heroku CLI plugins. While it is not a direct replacement for heroku-client, it offers functionalities that can be useful for extending the Heroku CLI with custom commands and integrations.

heroku-api

The heroku-api package is a Ruby client for the Heroku API. It provides similar functionalities to heroku-client but is intended for use in Ruby applications. It allows developers to manage Heroku apps, config vars, and other resources programmatically.

README

heroku-client

A wrapper around the v3 Heroku API.

• Install
• Usage
  • Generators
  • HTTP Proxies
• Caching
  • Custom caching
• Contributing
  • Running tests

Install

$ npm install heroku-client --save

Usage

To begin, require the Heroku module and create a client, passing in an API token:

const Heroku = require('heroku-client')
const heroku = new Heroku({ token: process.env.HEROKU_API_TOKEN })

heroku-client has get, post, patch, and delete functions which can make requests with the specified HTTP method to any endpoint:

// GET requests
heroku.get('/apps').then(apps => {
  // do something with apps
})

// POST requests
heroku.post('/apps').then(app => {})

// POST requests with body
heroku.post('/apps', {body: {name: 'my-new-app'}}).then(app => {})

// PATCH requests with body
heroku.patch('/apps/my-app', {body: {name: 'my-renamed-app'}}).then(app => {})

// DELETE requests
heroku.delete('/apps/my-old-app').then(app => {})

There is also an even more generic request function that can accept many more options:

heroku.request({
  method: 'GET',
  path: '/apps',
  headers: {
    'Foo': 'Bar'
  },
  parseJSON: false
}).then(response => {})

Generators

It's easy to get heroku-client working with generators. In this example, I'll use the co library to wrap a function that will get the list of all of my apps, and then get the dynos for each of those apps:

const co     = require('co')
const heroku = require('heroku-client')
const hk     = heroku.createClient({ token: process.env.HEROKU_API_KEY })

let main = function * () {
  let apps  = yield hk.get('/apps')
  let dynos = yield apps.map(getDynos)

  console.log(dynos)

  function getDynos(app) {
    return hk.get(`/apps/${app.name}/dynos`)
  }
}

co(main)()

Hooray, no callbacks or promises in sight!

HTTP Proxies

If you'd like to make requests through an HTTP proxy, set the HEROKU_HTTP_PROXY_HOST environment variable with your proxy host, and HEROKU_HTTP_PROXY_PORT with the desired port (defaults to 8080). heroku-client will then make requests through this proxy instead of directly to api.heroku.com.

Caching

heroku-client can optionally perform caching of API requests.

heroku-client will cache any response from the Heroku API that comes with an ETag header, and each response is cached individually (i.e. even though the client might make multiple calls for a user's apps and then aggregate them into a single JSON array, each required API call is individually cached). For each API request it performs, heroku-client sends an If-None-Match header if there is a cached response for the API request. If API returns a 304 response code, heroku-client returns the cached response. Otherwise, it writes the new API response to the cache and returns that.

To tell heroku-client to perform caching, add a config object to the options with store and encryptor objects. These can be instances of memjs and simple-encryptor, respectively.

var Heroku    = require('heroku-client');
var memjs     = require('memjs').Client.create();
var encryptor = require('simple-encryptor')(SECRET_CACHE_KEY);
var hk        = new Heroku({
  cache: { store: memjs, encryptor: encryptor }
});

Custom caching

Alternatively you can specify a custom cache implementation. Your custom implementation must define get(key, cb(err, value)) and set(key, value) functions.

Here's a sample implementation that uses Redis to cache API responses for 5-minutes each:

var redis        = require('redis');
var client       = redis.createClient();
var cacheTtlSecs = 5 * 60; // 5 minutes

var redisStore = {
  get: function(key, cb) {
    // Namespace the keys:
    var redisKey = 'heroku:api:' + key;
    client.GET(redisKey, cb);
  },

  set: function(key, value) {
    // Namespace the keys:
    var redisKey = 'heroku:api:' + key;
    client.SETEX(redisKey, cacheTtlSecs, value, function(err) {
      // ignore errors on set
    });
  }
};

var encryptor = require('simple-encryptor')(SECRET_CACHE_KEY);
var Heroku    = require('heroku-client');
var hk        = new Heroku({
  cache: {store: redisStore, encryptor: encryptor}
});

Contributing

Inspect your changes, and bump the version number accordingly when cutting a release.

Running tests

heroku-client uses ava for tests:

$ npm test